配置文件管理：分层配置系统与权限控制
引言
前面五章分别讲了 CLAUDE.md 项目规范（01）、Skills 系统（02）、MCP 服务器（03）、Subagents（04）和 Hooks 自动化（05）。本章不再重复这些内容，而是聚焦于底层配置系统的运行机制：配置文件放在哪、优先级怎么算、权限怎么控、沙箱怎么配。
五分钟上手：你的第一个配置
在深入理论之前，先看一个最常见的配置场景 — 给项目添加统一规则：
# 1. 在项目根目录创建 CLAUDE.md（项目规范，提交到 Git）
cat > CLAUDE.md << 'EOF'
# 项目规范
- 使用 TypeScript，不要写 any
- 组件使用 Composition API
- 提交信息使用中文
EOF
# 2. 在 .claude/ 下创建共享设置（提交到 Git）
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git *)"
]
}
}
EOF
# 3. 个人敏感配置（不提交到 Git）
cat > .claude/settings.local.json << 'EOF'
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "你的API密钥"
}
}
EOF
bash
三个文件，三个层级：CLAUDE.md 管规范，settings.json 管权限，settings.local.json 管密钥。这就是 Claude Code 配置的核心思路。
配置层级与优先级
Claude Code 使用五层作用域，层级越高优先级越高：
┌─────────────────────────────────────────────────────────┐
│ Layer 1 (最高) — Managed 策略 │
│ macOS: /Library/Application Support/ClaudeCode/ │
│ Linux: /etc/claude-code/ │
│ 作用: 企业IT统一部署，任何层都无法覆盖 │
├─────────────────────────────────────────────────────────┤
│ Layer 2 — 命令行参数 │
│ --model、--allowedTools 等启动参数 │
│ 作用: 临时覆盖，仅当前会话有效 │
├─────────────────────────────────────────────────────────┤
│ Layer 3 — 项目本地设置 │
│ .claude/settings.local.json │
│ 作用: 个人在本项目的覆盖配置，不提交到 Git │
├─────────────────────────────────────────────────────────┤
│ Layer 4 — 项目共享设置 │
│ .claude/settings.json │
│ 作用: 团队共享配置，提交到 Git │
├─────────────────────────────────────────────────────────┤
│ Layer 5 (最低) — 用户全局设置 │
│ ~/.claude/settings.json │
│ 作用: 个人默认配置，所有项目生效 │
└─────────────────────────────────────────────────────────┘
text
核心规则：同一配置项在多层定义时，高优先级覆盖低优先级。但有一个重要例外 — deny 规则在任何层级都生效，无法被高层 allow 覆盖。
配置合并示例
// ~/.claude/settings.json (Layer 5, 用户全局)
{
"model": "sonnet",
"permissions": {
"allow": ["Bash(npm *)", "Bash(git *)"]
}
}
// .claude/settings.json (Layer 4, 项目共享)
{
"permissions": {
"allow": ["Bash(pnpm *)"],
"deny": ["Bash(npm publish *)"]
}
}
json
最终生效：model = "sonnet"，允许 pnpm * 和 git *，但 npm publish 被拒绝（deny 规则始终生效）。
settings.json 详解
文件位置
| 范围 | 文件路径 | 是否提交 Git | 适用场景 |
|---|---|---|---|
| 用户全局 | ~/.claude/settings.json | 否 | 个人偏好，所有项目 |
| 项目共享 | .claude/settings.json | 是 | 团队规范，统一行为 |
| 项目本地 | .claude/settings.local.json | 否 | 个人密钥、本地调试 |
完整配置示例
在 settings.json 顶部添加 $schema 可以获得 IDE 自动补全：
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"model": "claude-sonnet-4-6",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)",
"Bash(git commit *)",
"Read(~/.zshrc)"
],
"deny": [
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
],
"defaultMode": "default"
},
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "FILE=$(jq -r '.tool_input.file_path'); [ -f \"$FILE\" ] && prettier --write \"$FILE\"; exit 0" }]
}
]
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1"
},
"language": "chinese",
"alwaysThinkingEnabled": true,
"autoMemoryEnabled": true,
"effortLevel": "high",
"plansDirectory": "./plans",
"enableAllProjectMcpServers": true,
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"filesystem": {
"allowWrite": ["/tmp/build"],
"denyRead": ["~/.aws/credentials"]
}
}
}
json
常用配置项速查
| 配置项 | 说明 | 示例值 |
|---|---|---|
model | 默认模型 | "claude-sonnet-4-6" |
permissions | 权限控制 | 见下节 |
hooks | 生命周期钩子（详见05-Hooks自动化） | JSON 配置 |
env | 环境变量 | {"FOO": "bar"} |
language | 响应语言 | "chinese" |
alwaysThinkingEnabled | 默认开启深度思考 | true |
autoMemoryEnabled | 自动记忆功能 | true |
effortLevel | 思考投入程度 | "low" / "medium" / "high" |
plansDirectory | 计划文件存放路径 | "./plans" |
enableAllProjectMcpServers | 自动启用项目 MCP 服务器 | true |
sandbox | 沙箱隔离配置 | JSON 配置 |
不要放到 settings.json 的配置
| 配置项 | 说明 |
|---|---|
autoConnectIde | 自动连接 IDE |
editorMode | 键绑定模式（normal/vim） |
showTurnDuration | 显示回合耗时 |
mcpServers | MCP 服务器定义（应在 .mcp.json 或 ~/.claude.json） |
权限系统
规则语法
权限规则格式为 Tool 或 Tool(参数匹配)：
Bash # 匹配所有 Bash 命令
Bash(npm run build) # 精确匹配
Bash(npm run *) # 通配符匹配
Read(./.env) # 读取当前目录 .env 文件
Read(~/.zshrc) # 读取 home 目录文件
Edit(src/**/*.ts) # 项目根目录相对路径
WebFetch(domain:example.com) # 限定域名
mcp__puppeteer__navigate # 匹配 MCP 特定工具
text
三种规则类型
{
"permissions": {
"allow": ["Bash(npm run *)", "Bash(git diff *)", "Read(src/**)"],
"deny": ["Bash(rm -rf *)", "Read(./.env)", "Write(~/.ssh/*)"],
"ask": ["Bash(git push *)", "Bash(npm publish *)"]
}
}
json
- deny — 直接拒绝，优先级最高
- ask — 弹出确认对话框
- allow — 自动批准
求值顺序：deny → ask → allow，第一条匹配的规则生效。deny 在任何层级都不可被覆盖。
defaultMode 权限模式
| 模式 | 说明 | 适用场景 |
|---|---|---|
default | 敏感操作前需确认（默认） | 新手学习阶段 |
acceptEdits | 自动批准文件编辑 | 日常开发 |
plan | 仅规划，不执行操作 | 代码审查 |
bypassPermissions | 跳过所有确认（危险） | 本地实验 |
关于 bypassPermissions 的实战取舍：这是很多熟手日常在用的模式（启动方式：claude --dangerously-skip-permissions，首次进入会询问是否信任当前目录）。敢用它一般有两个前提：一是全局 settings.json 里已经用 deny 兜住了红线（比如禁止删除 .git、禁止读密钥文件——deny 任何层级都覆盖不了它）；二是项目有 git 版本控制，就算 AI 改错删错，git checkout 一下就能回来。没有这两道保险之前，老老实实用 default 或 acceptEdits。
实际配置案例：团队前端项目
{
"permissions": {
"allow": [
"Read(*)",
"Glob(*)",
"Grep(*)",
"Bash(npm run *)",
"Bash(pnpm run *)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(git add *)",
"Bash(node *)"
],
"deny": [
"Bash(rm -rf *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
],
"defaultMode": "default"
}
}
json
沙箱配置
沙箱提供 OS 级别的文件系统和网络隔离，防止 Bash 命令造成意外损害。可在任意层级的 settings.json 中配置：
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"excludedCommands": ["docker *"],
"allowUnsandboxedCommands": true,
"filesystem": {
"allowWrite": ["/tmp/build", "~/.kube"],
"denyRead": ["~/.aws/credentials"]
},
"network": {
"allowedDomains": ["github.com", "*.npmjs.org"],
"deniedDomains": ["uploads.github.com"],
"allowLocalBinding": true,
"allowUnixSockets": ["/var/run/docker.sock"],
"httpProxyPort": null,
"socksProxyPort": null
},
"ignoreViolations": { "file": ["/tmp/*"], "network": ["localhost"] },
"enableWeakerNestedSandbox": false
}
}
json
配置项详解
| 属性 | 默认值 | 说明 |
|---|---|---|
enabled | false | 启用沙箱模式 |
autoAllowBashIfSandboxed | true | 沙箱内的 Bash 命令自动批准 |
excludedCommands | [] | 始终绕过沙箱的命令（如 docker） |
allowUnsandboxedCommands | true | 允许模型请求绕过沙箱（回退到权限系统） |
ignoreViolations | — | 忽略特定类别的沙箱违规 |
enableWeakerNestedSandbox | false | 嵌套沙箱兼容模式 |
网络配置
| 属性 | 说明 |
|---|---|
allowedDomains | 允许访问的域名白名单 |
deniedDomains | 禁止访问的域名黑名单 |
allowLocalBinding | 允许本地端口绑定 |
allowUnixSockets | 允许的 Unix socket 路径 |
httpProxyPort / socksProxyPort | 代理端口 |
安全提示：开放 /var/run/docker.sock 等同于放弃隔离，Docker API 可获取宿主机完整权限。
路径前缀规则
/— 绝对路径~/— 相对 home 目录./或无前缀 — 相对项目根目录（项目设置）或~/.claude（用户设置）
环境变量管理
常用环境变量
| 环境变量 | 说明 | 推荐配置位置 |
|---|---|---|
ANTHROPIC_AUTH_TOKEN | API 密钥 | settings.local.json |
ANTHROPIC_BASE_URL | API 端点 | settings.local.json |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS | 设为 1 开启 Agent Teams（实验性，见04章） | settings.json |
CLAUDE_CODE_ENABLE_TELEMETRY | 遥测开关 | settings.json |
CLAUDE_CODE_DISABLE_AUTO_MEMORY | 禁用自动记忆 | settings.json |
API_TIMEOUT_MS | API 超时（毫秒） | settings.json |
国内 API 端点配置
// .claude/settings.local.json（不提交到 Git）
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "你的API密钥",
"ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
"API_TIMEOUT_MS": "300000"
}
}
json
.gitignore 建议
# 忽略个人配置和敏感信息
.claude/settings.local.json
.claude/.env
.claude/secrets/
# 保留共享配置
!.claude/settings.json
!.claude/commands/
!.claude/skills/
!.claude/rules/
!.claude/agents/
gitignore
项目配置实战
团队协作项目结构
my-project/
├── CLAUDE.md # 项目规范（团队共享，详见01章）
├── .mcp.json # MCP 服务器（团队共享，详见03章）
├── .claude/
│ ├── settings.json # 项目权限和 hooks（提交到 Git）
│ ├── settings.local.json # 个人密钥（不提交）
│ ├── rules/ # 模块化规则（详见01章）
│ ├── agents/ # 自定义 Agent（详见04章）
│ ├── skills/ # 自定义技能（详见02章）
│ └── commands/ # 自定义命令
└── .gitignore # 包含 settings.local.json
text
Monorepo 多项目配置
Claude Code 会从当前目录向上遍历加载 CLAUDE.md，天然支持 Monorepo：
monorepo/
├── CLAUDE.md # 全局规范（所有子项目共享）
├── apps/
│ ├── web-app/
│ │ └── CLAUDE.md # Web App 特定规范
│ └── admin-panel/
│ └── CLAUDE.md # Admin Panel 特定规范
└── packages/
└── shared/
└── CLAUDE.md # 共享包特定规范
text
CI/CD 环境
# .github/workflows/claude.yml
name: Claude Code CI
on: [push]
jobs:
claude:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Claude Code
env:
ANTHROPIC_AUTH_TOKEN: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
npm install -g @anthropic-ai/claude-code
claude -p "检查代码质量并修复问题" --allowedTools "Read,Write,Edit,Bash"
yaml
第三方工具：CC-Switch 配置切换神器
手动编辑 ~/.claude/settings.json 来切换 API 端点很麻烦。CC-Switch（官网 ccswitch.io，Tauri 实现的跨平台桌面应用，15.2万+ Star，2026-11-07 核实）是一款开源的 AI CLI 可视化配置管理工具，解决了这个问题。
核心功能
- 一键切换 Provider：内置常见模型服务商列表（GLM、Qwen、DeepSeek、Kimi、官方 API、各类中转站等），点击"启用"即切换，下次启动 Claude Code 会话就使用对应端点
- 多工具统一管理：同时管理 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes Agent、Pi、MiniMax Code
- MCP 服务器管理：统一管理 MCP 服务器，支持 stdio、HTTP、SSE 三种传输方式
- Skills 管理：图形界面管理本地 Skills，支持备份、恢复、导出
- 提示词模板与会话管理：集中维护提示词模板，查看历史会话
- 多设备同步：通过坚果云等云盘同步配置到多台电脑
安装方式
# macOS（推荐，已收录进 Homebrew 主仓库）
brew install --cask cc-switch
# 或从 GitHub Releases 下载对应平台安装包
# macOS DMG / Windows 安装包 / Linux 包，地址见仓库右侧 Releases
bash
只从 ccswitch.io、GitHub Releases 或源码仓库获取——官方明确提示任何要求付费、充值或索取登录凭据的"CC Switch"网站都不是官方渠道。
使用场景
- 国内用户：一键切换 GLM / Qwen / DeepSeek 等国产模型端点，无需手动改 JSON
- 多站点切换：公益站额度用完一键切到备用站或付费站
- 多工具统一：Claude Code、Codex、Gemini CLI 等共用同一套配置
注意：切换后需重启 Claude Code 客户端。第三方 API 可能不支持 Claude Code 默认的 adaptive 思考类型，遇到报错时可以在 settings.json 中设置 "alwaysThinkingEnabled": false 尝试解决。
故障排查
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 配置不生效 | 文件位置错误 | 确认在 ~/.claude/ 或 .claude/ 下 |
| API 调用失败 | settings.local.json 配置错误 | 检查 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL |
| MCP 服务器无法连接 | mcpServers 放错了文件 | 移到 .mcp.json（详见03章） |
| 权限被拒绝 | deny 规则在某层生效 | 检查所有层的 deny 规则，deny 不可被覆盖 |
| Hook 没有执行 | 修改 hooks 后未重启 | Hook 配置修改后需重启会话（详见05章） |
| IDE 自动补全不工作 | 缺少 $schema | 在 settings.json 顶部添加 schema 引用 |
↑